package com.fowo.api.mp.service;

import com.fowo.api.mp.model.*;

/**
 * 公众号相关服务
 */
public interface OfficialAccountService {

    /**
     * 获取接口调用凭证
     * (https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Get_access_token.html)
     * @apiNote 获取的是服务端使用的调用凭证，不得公开到客户端，将会有严重安全问题
     */
    default String getAccessToken() {
        return getAccessToken(false);
    }

    /**
     * 公众平台的API调用所需的access_token
     * @apiNote 获取的是服务端使用的调用凭证，不得公开到客户端，将会有严重安全问题
     * @param forceUpdate 是否强制更新，访问的是调用次数限制接口，不要使用无条件的强制更新
     */
    String getAccessToken(boolean forceUpdate);

    /**
     * [公众号]服务器配置校验
     * (https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html)
     * @return 校验成功返回 nonce 原内容，否则返回 null
     */
    String checkSignature(CheckSignatureRequest request) throws Exception;

    /**
     * [公众号]发送模版消息
     * (https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Template_Message_Interface.html#%E5%8F%91%E9%80%81%E6%A8%A1%E6%9D%BF%E6%B6%88%E6%81%AF)
     * @param message 模版消息
     * @return 发送结果
     */
    WxResult sendTemplateMessage(WxTemplateMessage message) throws Exception;

    /**
     * 获取网页授权的跳转地址
     * (https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html)
     * @param redirectUrl 授权后重定向的回调链接地址
     * @param state 重定向后会带上state参数，开发者可以填写a-zA-Z0-9的参数值，最多128字节
     * @param userInfoScope 是否授权用户信息，如果为 false 表示静默授权（只能取到 openid)
     * @return 跳转地址
     */
    String getAuthorizeUrl(String redirectUrl, String state, boolean userInfoScope);

    /**
     * 通过code换取网页授权access_token
     * (https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html)
     * @param code 网页授权 code
     */
    OaAccessToken getAccessTokenByCode(String code) throws Exception;

    /**
     * 刷新access_token（如果需要）
     * @param refreshToken 填写通过access_token获取到的refresh_token参数
     */
    OaAccessToken getAccessTokenByRefresh(String refreshToken) throws Exception;

    /**
     * 拉取用户信息(需scope为 snsapi_userinfo)
     * @param accessToken 网页授权接口调用凭证,注意：此 access_token 是 OaAccessToken 中的 accessToken
     * @param openid 用户的唯一标识
     * @return 获取的用户信息的结果
     */
    WxUserInfo getUserInfoByAccessToken(String accessToken, String openid) throws Exception;

    /**
     * 通过code换取网页授权access_token并拉取用户信息
     * @param code 网页授权 code
     * @return 获取的用户信息的结果
     */
    WxUserInfo getUserInfoByCode(String code) throws Exception;

    /**
     * 为网页地址生成 wx.config 签名参数
     * @param url 需要生成签名参数的地址
     */
    JsApiConfigResult getJsApiConfig(String url) throws Exception;
}
